Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Overview:
This document describes the storage (or memory) responsibility of client arguments (or parameters). It first outlines the CORBA standard and then it goes into specific details pertaining to OpenDoc.
CORBA Standard1 :
In order to understand what are the storage (or memory) responsibility of client arguments, it is best to review the CORBA standard:
1) A client is responsible for providing storage for all arguments passed as in arguments.
2) A client is responsible forproviding storage for all out arguments and return results except in the following cases:
inout out return result
short 1 1 1
long 1 1 1
ushort 1 1 1
ulong 1 1 1
float 1 1 1
double 1 1 1
boolean 1 1 1
char 1 1 1
octet 1 1 1
enum 1 1 1
object reference 2 2 2
struct 1 1 1
union 1 1 1
string 1 3 3
sequence 1 4 4
array 1 1 3
any 4 4 4
Case 1:
The client is responsible for providing storage and managing release of the storage. That is, the system allocates storage which must be free using ORBFree() for the following types and directions: string/out, string/return, sequence/out, sequence/return, array/return, any/inout, any/out, any/return. For inout strings and sequences, the out result is constrained by the size of the type on input.
Case 2:
The client is responsible for providing the storage used to contain the object reference. When the reference is no longer needed, the client uses the release function to release the storage associated with the reference.
Case 3:
The ORB provides the storage for these returned parameters and results. The client is responsible for releasing the storage using ORBFree.
Case 4:
The client provides the storage for the structure which contains the description of the sequence or any and the client manages release of the storage and the descriptor. The ORB prvoides storage for the values returned and puts the pointers to this storage in the descriptor structures. The client is responsible for releasing this storage using ORBFree.
Implication to OpenDoc
If you are a client (i.e., caller) of an OpenDoc API,
If you are a callee (i.e, methods of OpenDoc classes),
in out inout
Allocation N/A ODNewPtr ODNewPtr
Deallocation N/A N/A N/A
Implication to Parts (i.e., client to OpenDoc API)
in out inout
Allocation SOMMalloc N/A SOMMalloc
ODNewPtr ODNewPtr
Stack Stack
Deallocation SOMFree SOMFree SOMFree
ORBFree ORBFree ORBFree
ODDisposePtr ODDisposePtr ODDisposePtr
Other Rules:
1) A callee must not modify in-parameters.
2) A callee must not store an in-parameter. You must duplicate the in-parameter.
3) Avoid ODObject/inout even though CORBA allows it.
If you want to change the state or content of an ODObject, an in-parameter is sufficient. If you want to return an ODObject, an out-parameter should be used.
ODObject/inout is strange because the incoming object may be deleted and a new object is created and returned. It is difficult to figure out whether the original object gets returned or not.
4) Don’t reallocate memory for string/inout and sequence/inout.
Since one cannot grow the buffer to more than the predetermined size, do NOT reallocate memory for these structs. Simply use the buffer provided.
1 The Common Object Request Borker: Architecture and Specification (p.98-99)
